<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<!-- Begin Header -->
<title>Gitblit</title>
<meta charset="utf-8">
<meta name="ROBOTS" content="INDEX">
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
		
<link rel="stylesheet" href="./bootstrap/css/bootstrap.css">
<link rel='shortcut icon' type='image/png' href='./gitblt-favicon.png' />
<link rel="stylesheet" href="./prettify/prettify.css" />
<script src="./prettify/prettify.js"></script>
<script src="./bootstrap/js/jquery.js"></script>
<script src="./bootstrap/js/bootstrap.min.js"></script>
</head>
<body onload='prettyPrint()'>		<!-- Navigation Bar -->
		<div class="navbar navbar-fixed-top">
			<div class="navbar-inner">
				<div class="container">
          			<a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse">
            			<span class="icon-bar"></span>
            			<span class="icon-bar"></span>
            			<span class="icon-bar"></span>
          			</a>
          			<a class="brand" href="./"><img src="./gitblt_25_white.png" alt="Gitblit"></img></a>
					<div class="nav-collapse">
						<ul class="nav">
							<li class='dropdown'> <!-- Menu -->
<a class='dropdown-toggle' href='#' data-toggle='dropdown'>about<b class='caret'></b></a>
<ul class='dropdown-menu'>
<li><a href='index.html'>overview</a></li>
<li><a href='features.html'>features</a></li>
</ul></li> <!-- End Menu -->
<li class='dropdown'> <!-- Menu -->
<a class='dropdown-toggle' href='#' data-toggle='dropdown'>documentation<b class='caret'></b></a>
<ul class='dropdown-menu'>
<li class='dropdown-submenu'> <!-- Submenu -->
<a tabindex='-1' href='#'>Gitblit GO</a>
<ul class='dropdown-menu'>
<li><a href='setup_go.html'>setup GO</a></li>
<li><a href='upgrade_go.html'>upgrade GO</a></li>
</ul></li> <!-- End Submenu -->
<li class='divider'></li>
<li class='dropdown-submenu'> <!-- Submenu -->
<a tabindex='-1' href='#'>Gitblit WAR</a>
<ul class='dropdown-menu'>
<li><a href='setup_war.html'>setup WAR</a></li>
<li><a href='upgrade_war.html'>upgrade WAR</a></li>
</ul></li> <!-- End Submenu -->
<li class='divider'></li>
<li class='dropdown-submenu'> <!-- Submenu -->
<a tabindex='-1' href='#'>Server Configuration</a>
<ul class='dropdown-menu'>
<li><a href='administration.html'>administration</a></li>
<li><a href='setup_authentication.html'>authentication</a></li>
<li><a href='setup_hooks.html'>push hooks</a></li>
<li><a href='setup_lucene.html'>lucene indexing</a></li>
<li><a href='setup_proxy.html'>reverse proxies</a></li>
<li><a href='setup_clientmenus.html'>client app menus</a></li>
<li><a href='setup_bugtraq.html'>bugtraq</a></li>
<li><a href='setup_mirrors.html'>mirrors</a></li>
<li><a href='setup_scaling.html'>scaling</a></li>
<li class='divider'></li>
<li><a href='setup_viewer.html'>Gitblit as a viewer</a></li>
</ul></li> <!-- End Submenu -->
<li class='divider'></li>
<li class='dropdown-submenu'> <!-- Submenu -->
<a tabindex='-1' href='#'>Client Usage</a>
<ul class='dropdown-menu'>
<li><a href='setup_transport_http.html'>using HTTP/HTTPS</a></li>
<li><a href='setup_transport_ssh.html'>using SSH</a></li>
<li><a href='eclipse_plugin.html'>using the Eclipse plugin</a></li>
</ul></li> <!-- End Submenu -->
<li class='divider'></li>
<li class='dropdown-submenu'> <!-- Submenu -->
<a tabindex='-1' href='#'>Tickets</a>
<ul class='dropdown-menu'>
<li><a href='tickets_overview.html'>overview</a></li>
<li><a href='tickets_using.html'>using</a></li>
<li><a href='tickets_barnum.html'>barnum</a></li>
<li><a href='tickets_setup.html'>setup</a></li>
<li><a href='tickets_replication.html'>replication & advanced administration</a></li>
</ul></li> <!-- End Submenu -->
<li class='divider'></li>
<li class='dropdown-submenu'> <!-- Submenu -->
<a tabindex='-1' href='#'>Plugins</a>
<ul class='dropdown-menu'>
<li><a href='plugins_overview.html'>overview</a></li>
<li><a href='plugins_extensions.html'>extension points</a></li>
</ul></li> <!-- End Submenu -->
<li class='divider'></li>
<li><a href='federation.html'>federation</a></li>
<li class='divider'></li>
<li><a href='properties.html'>settings</a></li>
<li><a href='faq.html'>faq</a></li>
<li class='divider'></li>
<li><a href='design.html'>design</a></li>
<li><a href='rpc.html'>rpc</a></li>
</ul></li> <!-- End Menu -->
<li class='dropdown'> <!-- Menu -->
<a class='dropdown-toggle' href='#' data-toggle='dropdown'>changelog<b class='caret'></b></a>
<ul class='dropdown-menu'>
<li><a href='releasecurrent.html'>current release</a></li>
<li><a href='releasehistory.html'>older releases</a></li>
</ul></li> <!-- End Menu -->
<li class='dropdown'> <!-- Menu -->
<a class='dropdown-toggle' href='#' data-toggle='dropdown'>links<b class='caret'></b></a>
<ul class='dropdown-menu'>
<li><a href='https://dev.gitblit.com'>dev.gitblit.com (self-hosted)</a></li>
<li class='divider'></li>
<li><a href='http://plugins.gitblit.com'>Plugins Registry</a></li>
<li class='divider'></li>
<li><a href='https://github.com/gitblit/gitblit'>Github</a></li>
<li><a href='https://github.com/gitblit/gitblit'>Issues</a></li>
<li><a href='http://groups.google.com/group/gitblit'>Discussion</a></li>
<li><a href='http://www.ohloh.net/p/gitblit'>Ohloh</a></li>
</ul></li> <!-- End Menu -->

						</ul>
					</div><!--/.nav-collapse -->
				</div>
			</div>
		</div><!-- end Navigation Bar -->
<div class='container'>
<!-- Begin Markdown -->
<h2 class="section" id='H1'><a href="#H1" class="sectionlink"><i class="icon-share-alt"> </i></a>Using the SSH transport</h2><p><em>SINCE 1.5.0</em></p><p>The SSH transport is a very exciting improvement to Gitblit. Aside from offering a simple password-less, public key workflow the SSH transport also allows exposes a new approach to interacting with Gitblit: SSH commands. The Gerrit and Android projects have to be thanked for providing great base SSH code that Gitblit has integrated.</p><p>You may watch an Asciinema screencast of using the SSH transport and it's command infrastructure <a href="https://asciinema.org/a/9342">here</a>.</p>
<h3 class="section" id='H2'><a href="#H2" class="sectionlink"><i class="icon-share-alt"> </i></a>Cloning & Pushing</h3><p>By default, Gitblit serves the SSH transport on port 29418, which is the same as Gerrit. Why was 29418 chosen? It's likely because it resembles the IANA port assigned to the git protocol (9418).</p><p>Gitblit will authenticate using username/password or public keys.</p>
<pre><code>git clone ssh://&lt;username&gt;@&lt;hostname&gt;:29418/myrepository.git
</code></pre>
<h3 class="section" id='H3'><a href="#H3" class="sectionlink"><i class="icon-share-alt"> </i></a>Setting up your account to use public key authentication</h3><p>Public key authentication allows you to operate in a password-less workflow and to separate your web login credentials from your git credentials. Setting up public key authentication is very simple. If you are working on Windows you'll need to install <a href="http://git-scm.com/download/win">Git for Windows</a>.</p><p>First you'll need to create an SSH key pair, if you don't already have one or if you want to generate a new, separate key.</p>
<pre><code>ssh-keygen
</code></pre><p><strong>NOTE:</strong> It is important to note that <em>ssh-keygen</em> generates a public/private keypair (e.g. id_rsa and id_rsa.pub). You want to upload the <em>public</em> key, which is denoted by the <em>.pub</em> file extension.</p>
<h4 class="section" id='H4'><a href="#H4" class="sectionlink"><i class="icon-share-alt"> </i></a>Uploading your public key from the command-line</h4><p>Then you can upload your <em>public</em> key right from the command-line.</p>
<pre><code>cat ~/.ssh/id_rsa.pub | ssh -l &lt;username&gt; -p 29418 &lt;hostname&gt; keys add
cat c:\&lt;userfolder&gt;\.ssh\id_rsa.pub | ssh -l &lt;username&gt; -p 29418 &lt;hostname&gt; keys add
</code></pre>
<h4 class="section" id='H5'><a href="#H5" class="sectionlink"><i class="icon-share-alt"> </i></a>Uploading your public key through the browser</h4>
<ol>
  <li>Navigate to your <em>profile</em> page from the dropdown user menu.</li>
  <li>Click the <em>SSH Keys</em> tab and paste your public key into the <em>Add SSH Key</em> form.</li>
  <li>Click the <em>Save</em> button</li>
</ol><p>Once you ave uploaded your public key you should be able to execute the following command without a password prompt.</p>
<pre><code>ssh -l &lt;username&gt; -p 29418 &lt;hostname&gt;
</code></pre>
<h3 class="section" id='H6'><a href="#H6" class="sectionlink"><i class="icon-share-alt"> </i></a>Setting up an SSH alias</h3><p>Typing the following command syntax all the time gets to be rather tedious.</p>
<pre><code>ssh -l &lt;username&gt; -p 29418 &lt;hostname&gt;
</code></pre><p>You can define an alias for your server which will reduce your command syntax to something like this.</p>
<pre><code>ssh &lt;alias&gt;
</code></pre><p>Create or modify your <code>~/.ssh/config</code> file and add a host entry. If you are on Windows, you'll want to create or modify <code>&lt;userfolder&gt;\.ssh\config</code>, where <em>userfolder</em> is dependent on your version of Windows. Most recently this is <code>c:\users\&lt;userfolder&gt;</code>.</p>
<pre><code>Host &lt;alias&gt;
    IdentityFile ~/.ssh/id_rsa
    User &lt;username&gt;
    Port 29418
    HostName &lt;hostname&gt;
</code></pre>
<h3 class="section" id='H7'><a href="#H7" class="sectionlink"><i class="icon-share-alt"> </i></a>SSH Commands</h3><p>Gitblit supports SSH command plugins and provides several commands out-of-the-box.</p>
<h4 class="section" id='H8'><a href="#H8" class="sectionlink"><i class="icon-share-alt"> </i></a>keys</h4><p>The <em>keys</em> command dispatcher allows you to manage your public ssh keys. You can list keys, add keys, remove keys, and identify the key in-use for the active session.</p>
<h5 class="section" id='H9'><a href="#H9" class="sectionlink"><i class="icon-share-alt"> </i></a>keys add</h5><p>Add an SSH public key to your account. This command accepts a public key piped to stdin.</p>
<pre><code>cat ~/.ssh/id_rsa.pub | ssh -l &lt;username&gt; -p 29418 &lt;hostname&gt; keys add
</code></pre>
<h5 class="section" id='H10'><a href="#H10" class="sectionlink"><i class="icon-share-alt"> </i></a>keys list</h5><p>Show the SSH public keys you have added to your account.</p>
<pre><code>ssh -l &lt;username&gt; -p 29418 &lt;hostname&gt; keys list
</code></pre>
<h5 class="section" id='H11'><a href="#H11" class="sectionlink"><i class="icon-share-alt"> </i></a>keys remove</h5><p>Remove an SSH public key from your account. This command accepts several input values, the most useful one is an index number which matches the index number displayed in the <code>list</code> command.</p>
<pre><code>ssh -l &lt;username&gt; -p 29418 &lt;hostname&gt; keys remove 2
</code></pre><p>You can also remove all your public keys from your account.</p>
<pre><code>ssh -l &lt;username&gt; -p 29418 &lt;hostname&gt; keys remove ALL
</code></pre>
<h5 class="section" id='H12'><a href="#H12" class="sectionlink"><i class="icon-share-alt"> </i></a>keys permission</h5><p>You may control the access permission for each SSH key. This is more of a safety feature than a security measure.</p>
<table>
  <thead>
    <tr>
      <th>Permission </th>
      <th>Description </th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>V </td>
      <td>SSH key may not be used for clone/fetch or push </td>
    </tr>
    <tr>
      <td>R </td>
      <td>SSH key may be used to clone/fetch </td>
    </tr>
    <tr>
      <td>RW </td>
      <td>SSH key may be used to clone/fetch and push </td>
    </tr>
  </tbody>
</table>
<h3 class="section" id='H13'><a href="#H13" class="sectionlink"><i class="icon-share-alt"> </i></a>Mac OSX Fonts</h3><p>Many of Gitblit's SSH commands rely on ANSI border characters to provide a pretty presentation of data. Unfortunately, the fonts provided by Apple - while very nice - don't work well with ANSI border characters. The following public domain fixed-width, fixed-point, bitmapped fonts work very nicely. I find the 6x12 font with a line spacing of ~0.8 to be quite acceptable.</p><p><a href="6x12.dfont">6x12.dfont</a><br/><a href="6x13.dfont">6x13.dfont</a><br/><a href="7x13.dfont">7x13.dfont</a><br/><a href="7x14.dfont">7x14.dfont</a>
<!-- End Markdown -->
<div ><ul class="pager"><li class="previous"><a href="setup_transport_http.html">&larr; using HTTP/HTTPS</a></li> <li class="next"><a href="eclipse_plugin.html">using the Eclipse plugin &rarr;</a></li></ul></div><footer class="footer"><p class="pull-right">generated 2016-06-22</p>
<p>The content of this page is licensed under the <a href="http://creativecommons.org/licenses/by/3.0">Creative Commons Attribution 3.0 License</a>.</p>
</footer>
</div>
</body>
</html>